﻿// -----------------------------------------------------------------------
// <copyright file="IException.cs" company="Company">
// Company 2011
// </copyright>
// -----------------------------------------------------------------------

using System;
using System.Collections;
using System.Reflection;
using System.Runtime.InteropServices;
using System.Runtime.Serialization;
using System.Security;

namespace Company.IO.Interfaces
{
    /// <summary>
    /// Represents errors that occur during application execution.
    /// </summary>
    [ComVisible(true)]
    [Guid("a5fdd267-af28-4eb7-a4cd-3fdf33d142cf")]
    public interface IException : ISerializable
    {
        /// <summary>
        /// Gets a collection of key/value pairs that provide additional user-defined information about the exception.
        /// </summary>
        IDictionary Data { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets a message that describes the current exception.
        /// </summary>
        string Message { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets the Exception instance that caused the current exception.
        /// </summary>
        IException InnerException { get; }

        /// <summary>
        /// Gets the method that throws the current exception.
        /// </summary>
        MethodBase TargetSite { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets a string representation of the immediate frames on the call stack.
        /// </summary>
        string StackTrace { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets or sets a link to the help file associated with this exception.
        /// </summary>
        string HelpLink { get; set; }

        /// <summary>
        /// Gets or sets the name of the application or the object that causes the error.
        /// </summary>
        string Source { [SecuritySafeCritical]
        get; set; }

        /// <summary>
        /// Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.
        /// </summary>
        int HRESULT { [SecuritySafeCritical]
        get; set; }

        /// <summary>
        /// When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.
        /// </summary>
        /// <returns>
        /// The first exception thrown in a chain of exceptions. 
        /// If the InnerException property of the current exception is a null reference (Nothing in Visual Basic), 
        /// this property returns the current exception.
        /// </returns>
        IException GetBaseException();

        /// <summary>
        /// Creates and returns a string representation of the current exception.
        /// </summary>
        /// <returns>A string representation of the current exception.</returns>
        [SecuritySafeCritical]
        string ToString();

        /// <summary>
        /// Gets the runtime type of the current instance.
        /// </summary>
        /// <returns>A Type object that represents the exact runtime type of the current instance.</returns>
        Type GetType();
    }
}